GetNamedResource

GetNamedResource
Header:	Resources.h		Carbon status:	Supported

Gets a named resource.

Handle GetNamedResource (
    ResType theType, 
    ConstStr255Param name
);

theType: The resource type of the resource about which you wish to retrieve data.
name: A name that uniquely identifies the resource about which you wish to retrieve data. Strings passed in this parameter are case-sensitive.

function result

If the function finds the specified resource entry in one of the resource maps and the entry contains a valid handle, the function returns that handle. If the entry contains a handle whose value is NULL, and if you haven’t called the SetResLoad function with the load parameter set to FALSE, GetNamedResource attempts to read the resource into memory.

If the function can’t find the resource data, it returns NULL, and the ResError function returns the result code resNotFound. The function also returns NULL if the resource data to be read into memory won’t fit, in which case ResError returns an appropriate Memory Manager result code. If you call GetNamedResource with a resource type that can’t be found in any of the resource maps of the open resource forks, the function returns NULL as well, but ResError returns the result code noErr. You should always check that the value of the returned handle is not NULL.

DISCUSSION

The function searches the resource maps in memory for the specified resource. The resource maps in memory, which represent all the open resource forks, are arranged as a linked list. When the function searches this list, it starts with the current resource file and progresses through the list in order (that is, in reverse chronological order in which the resource forks were opened) until it finds the resource’s entry in one of the resource maps.

You can change the resource map search order by calling the UseResFile function before GetNamedResource.

To include ROM-resident system resources in the Resource Manager’s search of the resource maps for open resource forks, use the RGetResource function.

SPECIAL CONSIDERATIONS

This function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.

AVAILABILITY

Supported in Carbon. Available in Mac OS 8.1 and later when Carbon 1.0.2 or later is present.